aron-conventional-commits

A human-readable set of conventional commits, with version rules and changelog groupings

• Human-readable sentence case commits format
• Sometimes strict and sometimes loose commit formats
• Not only Monorepo but also single-package repositories
• Release rules are used for semantic analysis of semantic releases to bump versions automatically
• Groups are used to group changelogs
• This also applies to the conventional-changelog ecosystem

Commit Message Header

The header has a particular format that includes a Type, a Target, and a Summary:

Type(Target): Summary
  ┊     ┊
  ┊     └─⫸ Target: Workspace, Package or Role
  ┊
  └─⫸ Type: Bump, Feat, New, Perf, Add, Update, Improve, Fix, Depreciate, Drop, Docs, Upgrade, Revert, Example, Test, Refactor, Chore, Misc

• Type
  • Sentense case only
• Target
  • Sentense case only
  • Accept starting with Markdown characters ` * _ # ~
  • Can be omitted in one workspace
• Summary
  • Sentense case only
  • Accept starting with Markdown characters ` * _ # ~
  • No period at the end

Semver Commits

Such commits result in version bumps.

Patch

Perf Add Update Improve Fix Depreciate Drop Upgrade Revert Bump(Patch) Docs(README)

Bug Fixes

Changelog +0.0.1 A change to a system or product designed to handle a programming bug/glitch.

Fix: <Summary>
Fix(Target): <Summary>

_{🟢 Good for a monorepo}

Fix(CSS): HEX codes were incorrectly parsed as selectors
     ┊    ┊
     ┊    └─⫸ A brief description of the specific error
     ┊
     └─⫸ CSS is a workspace package

_{🔴 Bad for a monorepo}

Fix: Fix issues by extracting hex codes with strict rules
   ┊  ┊                 ┊
   ┊  ┊                 └─⫸ Describe the problem rather than the solution
   ┊  ┊
   ┊  └─⫸ Don't repeat the word `Fix` in Summary
   ┊
   └─⫸ Without a `(Target)`, the viewer cannot identify the participating workspace

Performance Upgrades

Changelog +0.0.1

Perf: <Summary>
Perf(Target): <Summary>

Example

Perf: Refresh cache when configuration changes

Additions

Changelog +0.0.1

Add: <Summary>
Add(Target): <Summary>

Example

Add(CSS): Option `.preference` for default theme

Improvements

Changelog +0.0.1

Improve: <Summary>
Improve(Target): <Summary>

Example

Improve(Home): Swap the order of **Feature** and **Pricing**

Updates

Changelog +0.0.1 Static content updates such as articles, news, about, profile, etc.

Update: <Summary>
Update(Target): <Summary>

Example

Update(Team): The member's job title changed

Upgrades

Changelog +0.0.1 Upgrade environment, system, dependencies, etc.

Upgrade: <Summary>
Upgrade(Target): <Summary>

Example

Upgrade(Compiler): Dependency `@master/css@^2.0.0`

Deprecations

Changelog +0.0.1 Alias: Drop Deprecate features, options, parameters, units, pages, etc.

Depreciate: <Summary>
Depreciate(Target): <Summary>

Example

Drop(Normal CSS): `--font-mono` `--font-sans` `--font-serif` CSS variables

Reversions

Changelog +0.0.1

Revert: "<Reverted Commit Header>"


This reverts commit <Reverted Commit Hash>.

If you are using Git Graph extension for VSCode, Clicking Revert will automatically generate the following format:

Revert "<Reverted Commit Header>"


This reverts commit <Reverted Commit Hash>.

Example

Revert "Fix(Repo): PeerDependencies -> Dependencies"


This reverts commit 779347237eef77e9137f88095e1fb813e5101c2b.

Update README _^Ungrouped

+0.0.1 The README.md of the NPM package can only be updated by releasing a new version. At this time, it's very convenient to trigger the patch through:

Docs(README): <Summary>

Docs(README): Features section

It's reasonable to update README.md by bumping to the patch version because the documentation is part of this version.

Manual

+0.0.1 Manually bump a patch version due to special reasons.

Bump(Patch): <Summary>

Example

git commit --allow-empty -m 'Bump(Patch): `+0.0.1`'

Minor

Feat New Bump(Minor)

New Features

Changelog +0.1.0 Alias: New

Feat: <Summary>
Feat(Target): <Summary>

Example

New(Syntax): A new shorthand `WxH` for `width:` and `height:`

Manual

+0.1.0 Manually bump a minor version due to special reasons.

Bump(Minor): <Summary>

Example

git commit --allow-empty -m 'Bump(Minor): `+0.1.0`'

Major

Bumping to the next major version should be triggered manually by the manager rather than relying on a flag in a given commit.

_Format

Bump(Major): <Summary>

No clear motivation for <Summary> yet? Hit Version or the next version, like v2.0.0.

_{🟢 Good for a monorepo}

git commit --allow-empty -m 'Bump(Major): Master CSS v2.0'

This is just a commit used to trigger version analysis, don't be obsessed with changes in files, so add --allow-empty

Other Commits

Trivial routine commits include test cases, examples, and environment configurations.

Docs Tests Example Chore Misc

Documentation

Docs: <Summary>
Docs(Target): <Summary>

Example

Docs(CSS): Initialize Master CSS with custom configuration

Tests

Test: <Summary>
Test(Target): <Summary>

Example

Test(Syntax): Check CSS rules for `WxH` output

Examples

Example: <Summary>
Example(Target): <Summary>

Example

Example(Next.js 13): Update to layouts RFC

Miscellaneous

• Alias: Chore or no prefix

Misc: <Summary>
Misc(Target): <Summary>
<Summary>

Example

Chore: Update README.md

I prefer no prefix; having to keep prefixing every frequent trivial item is annoying, and marking trivial items doesn't make much sense.

_{🟢 Better day-to-day development experience}

Update README.md